package com.cxx.purchasecharge.core.config;

import java.util.Collection;

public abstract interface ICxxProperties
{
    /**
     * Returns the properties for the specified group, using the filepath as the 
     * directory to retrieve the properties.  The filepath is only used for
     * file-based implementations. In the config server implementation the filepath is ignored.
     * 
     * @param filePath
     * @param groupName
     * @return A CxxProperties instance for the group.
     * @throws ConfigException If any errors were encountered while retrieving the properties 
     * or the properties could not be found.
     * @throws ResourceNotFoundException
     *          If the resourceName does not exist or is not assigned to an hln.
     * @throws IllegalArgumentException If filePath is null or empty
     * @throws IllegalArgumentException If groupName is null or empty
     */
    public CxxProperties getProperties(String filePath, String groupName) throws ConfigException;
    
    /**
     * Returns the properties for the specified group.  If the properties
     * cannot be found using the given arguments an ConfigException is thrown.
     * 
     * @param groupName
     * @return A CxxProperties instance for the group.
     * @throws ConfigException If any errors were encountered while retrieving the properties 
     * or the properties could not be found.
     * @throws ResourceNotFoundException
     *          If the resourceName does not exist or is not assigned to an hln.
     * @throws IllegalArgumentException If groupName is null or empty
     */
    public CxxProperties getProperties(String groupName) throws ConfigException;

    /**
     * Returns a Collection of CxxProperties from the specified list of groups, using the filepath as the 
     * directory to retrieve the properties.  The filepath is only used for
     * file-based implementations. In the config server implementation the filepath is ignored.
     * 
     * If the properties cannot be found using the given arguments an ConfigException 
     * is thrown.
     * 
     * @param filePath
     * @param groupNames
     * @return A Collection of CxxProperties objects.
     * @throws ConfigException If any errors were encountered while retrieving the properties
     * or the properties could not be found.
     * @throws ResourceNotFoundException
     *          If the resourceName does not exist or is not assigned to an hln.
     * @throws IllegalArgumentException If filePath is null or empty
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public Collection<CxxProperties> getProperties(String filePath, Collection<String> groupNames)
            throws ConfigException;
    
    /**
     * Returns a Collection of CxxProperties from the specified list of groups 
     * If the properties cannot be found using the given arguments an ConfigException 
     * is thrown.
     * 
     * @param groupNames
     * @return A Collection of CxxProperties objects.
     * @throws ConfigException If any errors were encountered while retrieving the properties
     * or the properties could not be found.
     * @throws ResourceNotFoundException
     *          If the resourceName does not exist or is not assigned to an hln.
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public Collection<CxxProperties> getProperties(Collection<String> groupNames)
            throws ConfigException;

    /**
     * Returns a GroupMap object from the specified list of groups, using the filepath as the 
     * directory to retrieve the properties.  The filepath is only used for
     * file-based implementations. In the config server implementation the filepath is ignored.
     * 
     * If the properties cannot be found using the given arguments an ConfigException is thrown.
     * 
     * The use of a wildcard "*" is supported in the groupNames as long as it isn't
     * the first character and it appears as a suffix.  For example "d*" could be used
     * to return CxxProperties for both database and directory groups.
     * 
     * @param filePath
     * @param groupNames
     * @return A GroupMap object.
     * @throws ConfigException If any errors were encountered while retrieving the properties
     * or the properties could not be found.
     * @throws ResourceNotFoundException
     *          If the resourceName does not exist or is not assigned to an hln.
     * @throws IllegalArgumentException If filePath is null or empty
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public GroupMap getPropertiesMap(String filePath, Collection<String> groupNames)
            throws ConfigException;
    
    /**
     * Returns a GroupMap object from the specified list of groups. If the properties
     * cannot be found using the given arguments an ConfigException is thrown.
     * 
     * The use of a wildcard "*" is supported in the groupNames as long as it isn't
     * the first character and it appears as a suffix.  For example "d*" could be used
     * to return CxxProperties for both database and directory groups.
     * 
     * @param groupNames
     * @return A GroupMap object.
     * @throws ConfigException If any errors were encountered while retrieving the properties
     * or the properties could not be found.
     * @throws ResourceNotFoundException
     *          If the resourceName does not exist or is not assigned to an hln.
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public GroupMap getPropertiesMap(Collection<String> groupNames)
            throws ConfigException;
    
}
